<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Labels</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
    <META name="generator" content="Microsoft FrontPage 4.0">
  </HEAD>

  <BODY lang="EN-US">
    <H1>Labels</H1>

    <P>A label is a name associated with an address. Labels are used to make code easier to read.
    For example, instead of "call 0x103f2d", the instruction might read "call printf". The name
    "printf" has been associated with the address "0x103f2d". In other words, the address
    "0x103f2d" has been labeled printf.</P>

    <H3><A name="LabelName"></A>Label Name</H3>

    <BLOCKQUOTE>
      <P>All labels have an assigned symbol name which has either explicitly been established or a
      default generated name. When assigning a label name (or any other namespace or symbol name)
      the following naming restrictions apply:</P>

      <UL>
        <LI><B>Reserved Dynamic Name Pattern</B> - certain dynamic name patterns are reserved for
        Ghidra use and may not be explicitly set. A dynamic pattern generally consists of a default
        prefix (<I>SUB_, LAB_, DAT_, UNK_, EXT_, FUN_, OFF_</I>) followed by an address (e.g.,
        <I>LAB_01234567</I>).</LI>

        <LI><B>Space and Non-printable Characters Not Allowed</B> - a blank space character or
        other non-printable ASCII character (e.g., backspace, linefeed, etc.) are not permitted
        within a name</LI>

        <LI><B>Length Limit of 2000</B> - the name length may not exceed 2000 characters/bytes</LI>
      </UL>

      <P><IMG src="help/shared/note.png" alt="Note:"> In addition to the above restrictions, the
      use of '::' within a label name may cause problems with certain name edit dialogs which may
      use this as a namespace separator.</P>
    </BLOCKQUOTE>

    <H3><A name="LabelSource"></A>Label Source</H3>

    <BLOCKQUOTE>
      <P>Labels can be created or renamed by importing information, when auto-analysis is
      performed, or directly by the user. The label source indicates how the label was created or
      renamed.</P>

      <UL>
        <LI><B>User Defined -</B> Label name specified by the user.</LI>

        <LI><B>Imported -</B> Label named during the import of the program or by some other
        imported information (for example, external libraries or C libraries.)</LI>

        <LI><B>Analysis -</B> Label created by auto-analysis that do not have default names.</LI>

        <LI><B>Default -</B> Label with a default name. (Ghidra generally creates default-named
        symbols at any address that is referenced by some other location.)</LI>
      </UL>
    </BLOCKQUOTE>

    <H3><A name="DefaultLabel"></A>Default Labels</H3>

    <BLOCKQUOTE>
      <P>Some labels are automatically generated during disassembly. They use a standard naming
      convention to derive the symbolic name from the address. The current convention is to use a
      prefix that gives some information about what is at the address, followed by the address. For
      example, the automatic label generated for address "0x01234" would be "LAB_01234" if there is
      code at that address. If there was a data item at that address, the label would be
      "DAT_01234". Labels with auto-generated names are known as <I>default</I> labels. The
      importer, auto-analysis, or the user can also create labels (or rename default labels) using
      more meaningful names.<BR>
      Default label prefixes can be any of the following:</P>
    </BLOCKQUOTE>

    <UL>
      <LI><B>EXT -</B> indicates address is an external entry point.</LI>

      <LI><B>FUN -</B> indicates there is a function at the address.</LI>

      <LI><B>SUB -</B> indicates that code at the address has at least one "call" to it.</LI>

      <LI><B>LAB -</B> indicates there is code at the address.</LI>

      <LI><B>DAT -</B> indicates there is a data item at the address.</LI>

      <LI><B>OFF -</B> indicates that the associated address is offcut, i.e. inside of an
      instruction or data item.</LI>

      <LI><B>UNK -</B> default when one of the above cannot be recognized.</LI>
    </UL>

    <H3><A name="LabelProperties"></A>Label Properties</H3>

    <UL>
      <LI><B>Entry Point -</B> Indicates that the address associated with this label is an external
      entry point. External entry points are those addresses that can be used to initiate execution
      from outside the program. Most programs have a single "main" entry point. (Usually having the
      label "Entry".) Shared libraries (DLLs) usually have many entry points, one for each function
      in the library. Since the "entry point" property is really associated with an address and not
      a particular label, all labels at an address share this property.</LI>

      <LI><B><A name="Primary"></A>Primary -</B> Indicates that this label will be the one used to
      represent the address everywhere the address is displayed, such as in the operand field of an
      instruction. Since multiple labels can be associated with an address, one and only one must
      be designated as primary.</LI>
    </UL>

    <H2><A name="AddEditDialog"></A>Add/Edit Label Dialog</H2>

    <P>The <I>Add Label</I> dialog and the <I>Edit Label</I> dialog are identical except for the
    title and the way the dialog's fields are initialized. The <I>Add Label</I> dialog will be
    filled in with suggested values for all fields. The <I>Edit Label</I> dialog, on the other hand
    will be filled in with the current values of the label being edited.</P>

    <TABLE x-use-null-cells="" width="100%">
      <TBODY>
        <TR>
          <TD align="center" width="100%"><IMG src="images/AddLabel.png" border="0"></TD>
        </TR>
      </TBODY>
    </TABLE><BR>
    <BR>

    <P><IMG src="help/shared/note.png" alt="Note:"> If you add a label where there is a function
    with a default label name, the label you add will become the function's new name.&nbsp;<BR>
    </P>

    <H3>Dialog Fields</H3>

    <BLOCKQUOTE>
      <P><I><B>Enter Label</B></I></P>

      <BLOCKQUOTE>
            Text field for entering the name of the label. A combo box is included which allows
            selecting recently used label names. 

            <P>You may enter a namespace path in this text field that follows the format:<BR>
            </P>
<PRE>
    &lt;namespace_name1&gt;::&lt;namespace_name2&gt;::&lt;...&gt;::&lt;label_text&gt;
       
</PRE>
            For example, the following string denotes a full namespace path that starts at the
            <B>Global</B> namespace and ends at the label name <TT>myLabel</TT>:<BR>
		<PRE>
		Global::foo::bar::myLabel
		       
		</PRE>
            The namespace in the <I>Namespace</I> combo box will be used as the parent namespace
            for the label name and any included namespaces. However, if the you provide a namespace
            path that starts with <B>Global</B>, then the value of the <I>Namespace</I> combo box
            will be ignored.
      </BLOCKQUOTE>

      <P><I><B>Namespace</B></I></P>

      <BLOCKQUOTE>
          <P>The containing namespace for the label or function. </P>
          <P>The applicable namespaces are based upon the current address and symbol type. 
          The namespace combobox
          will initially be populated with the most obvious choices for that location, as well 
          any recently chosen namespaces.</P> 
          <P>Next to the combobox, there is a browse button which can be pressed to bring up the 
          <A href="#NamespaceChooserDialog">Namespace Chooser Dialog</A>. From this chooser dialog,
          any namespace in the program can be selected. However, not all namespaces are applicable
          to all locations. For example, you can't put a function into another function's namespace.
          If the namespace is not applicable to the current location, the selected namespace will
          still appear in the namespace field, but you will get an error when the OK button is 
          pressed.</P>

        <BLOCKQUOTE>
          <P><IMG src="help/shared/note.png" alt="Note:">This field is disabled when the namespace
          at that location can't be changed. For example, parameters and local variables can only
          have the enclosing function as its namespace. <BR>
          </P>
        </BLOCKQUOTE>
      </BLOCKQUOTE>

      <P><I><B>Entry Point</B></I></P>

      <BLOCKQUOTE>
        Sets the entry point property for address associated with this label. Setting this
          property on one symbol, changes it for all symbols at the same address.</LI>
        
      </BLOCKQUOTE>

      <P><I><B>Primary</B></I></P>

      <BLOCKQUOTE>
        Sets the primary property for this symbol. If there is only one symbol at this
          address, the checkbox will be selected and disabled, since it must be primary. Whenever
          the checkbox is selected, it will be disabled because the only way to make a symbol
          become non-primary is to select another symbol at the same address and make it primary.
          This ensures that there will always be one label that is primary. If there is a function
          at this address and you add a new label, the checkbox will be enabled such that if you
          select the checkbox, the function is renamed to the new label that you entered.&nbsp; The
          function symbol must always be the primary symbol.
        
      </BLOCKQUOTE>
       <P><I><B>Pinned</B></I></P>
      <BLOCKQUOTE>
        Sets the label to pinned.  A pinned label will not move if the image base is changed
          or a memory block is moved.  A label that is not pinned, will move with the code
          or data if a memory block is moved or the image base is changed.  Also, a pinned
          label will not be removed if the memory block that contains it is removed.  Only code, 
          data, or function labels may be pinned.
      </BLOCKQUOTE>
      
    </BLOCKQUOTE>
	<H2><A name="NamespaceChooserDialog"></A>Namespace Chooser Dialog</H2>
	<BLOCKQUOTE>
	
	      <P>The Namespace Chooser Dialog allows you to choose namespaces that have been defined
	      in the current program. It presents a drop-down text field where you can begin typing
	      the name of a namespace and a drop-down window will appear showing a list of 
	      all namespaces that match the typed text.</P>
	     

      <P align="center"><IMG border="0" src="images/ChooseNamespace.png" alt=""><BR>
       <I>Namespace Chooser Dialog</I></P>
       
       <P>There are several modes that determine how the typed text is used to match against all
       program namespaces. The mode can be changed by pressing on the symbol(s) shown on the far
       right of the text field.  You can also change the search mode using <B>Ctrl Down</B> and
       <B>Ctrl Up</B> to change the mode forward and backward, respectively. Regardless of the mode,
       the searches are not case sensitive.</P>
       <P>These modes are:</P>
       
       <UL>
       <LI><B>Starts With ^</B> - In this mode, the typed text will match all namespaces that
       have a base name (not path) that starts with the typed text.</LI>
       <LI><B>Contains <I>()</I></B> - In this mode, the typed text will match all namespaces that
       have the typed text anywhere in its full namespace path. </LI>
       <LI><B>Wildcard <I>*?</I></B> - In this mode, the typed text may contain wildcard characters
       which will be used to create a pattern for matching against the full namespace path. The
       wildcard char '*' will match 0 or more characters, while the wildcard char '?' will match any
       single character. </LI>
       </UL>
       
	</BLOCKQUOTE>


    <H2><A name="OperandLabelDialog"></A>Set Label Dialog</H2>

    <BLOCKQUOTE>
      <P>Normally, the primary label is used to replace an address reference in the operand field
      of an instruction or data item. Ghidra allows users to change which symbol is used to replace
      the address using the <I>Set Label</I> dialog.</P>
    </BLOCKQUOTE>

    <TABLE x-use-null-cells="" width="100%">
      <TBODY>
        <TR>
          <TD align="center" width="100%"><IMG src="images/SetLabel.png" border="0"></TD>
        </TR>
      </TBODY>
    </TABLE><BR>
    <BR>

    <BLOCKQUOTE>
      <H3>Label</H3>

      <BLOCKQUOTE>
        <P>The list in the combo box will show all symbols associated with the address shown in the
        dialog title. Choosing a label from the list will cause that symbol to be associated with
        the operand reference being modified. Typing in a new name will cause a new symbol to be
        created at the target address before associating it with the operand reference.</P>
      </BLOCKQUOTE>
    </BLOCKQUOTE>

    <H2><A name="LabelOperations"></A>Label Operations</H2>

    <H3><A name="Add_Label"></A>Adding a Label</H3>

    <BLOCKQUOTE>
      <P>Adding a label will place a label at a particular address in a listing. Labels may be of
      any length but may not contain spaces. To add a label:</P>

      <OL>
        <LI>Right-click and choose the <B>Add Label</B> menu option.</LI>

        <LI>Enter the name of the label in the text field (or accept the suggested default).</LI>

        <LI>Change any of the default options (see <A href="#AddEditDialog">Label Dialog</A>)</LI>

        <LI>Press the <B>OK</B> button.</LI>
      </OL>
    </BLOCKQUOTE>

    <BLOCKQUOTE>
      <P><IMG src="help/shared/note.png" alt="Note:">Adding a label to an address where there is a
      function with a default name results in the function name becoming the new label name.</P>
    </BLOCKQUOTE>

    <H3><A name="Edit_Label"></A>Renaming a Label</H3>

    <BLOCKQUOTE>
      <P>To change the name of a label or referenced label appearing in an operand:</P>

      <OL>
        <LI>Right-click on the label, or referenced label appearing in an operand, then
         choose the <B>Edit Label</B> item from the popup menu. </LI>

        <LI>Enter the new name of the label in the text field in the <B><A href=
        "#AddEditDialog">Label</A></B> dialog.</LI>

        <LI>Press the <B>OK</B> button.</LI>
      </OL>

      	<P><IMG src="help/shared/note.png" alt="Note:">If the label appearing in an operand corresponds 
      	to an external location the <B>Edit Label</B> action will be replaced by <B>Edit External Location</B>. 

    </BLOCKQUOTE>
    
    <H3><A name="Edit_External_Location"></A>Edit External Location</H2>

    <BLOCKQUOTE>
      <P>Similar to editing a label associated with the primary reference of an operand, an 
      external location referenced by an operand may be renamed or modified.  Right-click on the operand which references an external location
      and choose the <B>Edit External Location</B> menu option 
      (see Symbol Tree - 
      <A href="help/topics/SymbolTreePlugin/SymbolTree.htm#Edit_External_Location">Edit External Location</A>
      for more discussion on the use of the edit dialog).</P>
    </BLOCKQUOTE>

    <H3><A name="Remove_Label"></A>Removing a Label</H3>

    <BLOCKQUOTE>
      <P>Labels may or may not be eligible for removal depending on the following rules:</P>

      <UL>
        <LI>Labels that have no references to them can always be removed.</LI>

        <LI>Labels at addresses that contain more than one label can always be removed.</LI>

        <LI>"Default" labels with at least one references and no other labels at that address can
        not be removed. (The menu option will be disabled.)</LI>

        <LI>"User-defined" labels with at least one reference and no other labels at that address
        can be removed, but will be replaced with a "default" label at that address.</LI>

        <LI>A "default" function label cannot be removed if there are no other labels at the
        address. To remove a "default" function label, you must remove the function itself.</LI>

        <LI>A "user-defined" function label can be removed. If there are no other labels at the
        address then the function label becomes a "default" label. If there are other labels at the
        address, one of these will become the new function label.<BR>
        </LI>
      </UL>

      <P>To remove a label:</P>

      <OL>
        <LI>Right-click on the label to be removed and choose the <B>Remove Label</B> menu
        option.</LI>
      </OL>

      <P align="left"><IMG src="help/shared/note.png" border="0"> <I>Ghidra gives no confirmation
      on <B>Remove Label</B>. A status message is displayed if you try to remove a default function
      label.</I></P>
    </BLOCKQUOTE>

    <H3><A name="Set_Namespace"></A>Setting the Namespace</H3>

    <BLOCKQUOTE>
      <P>A <I>Namespace</I> defines a scope, such that symbol names are unique <I>within</I> a
      namespace. The types of namespaces that Ghidra supports are <I>Global</I>, <I>External</I>,
      <I>Function</I>, <I>Class</I>, and <I>Generic</I> namespaces that reside in the global
      namespace.</P>

      <P>To set the namespace:</P>

      <OL>
        <LI>Right click on a symbol and choose the <B>Edit Label</B> menu option.</LI>

        <LI>
          Select a namespace from the <I>namespace</I> combo-box in the <B><A href=
          "#AddEditDialog">Label</A></B> dialog.  Or, you may enter a new namespace with the label using "::" as a 
            name separator.  If a specified namespace does not exist a simple-namespace 
            will be created. 
             </LI>  
          </UL>
        </LI>
      </OL>
      <P align="left"><IMG src="help/shared/note.png" border="0"> Any use of a class-namespace requires that it first be
            created prior to associating a label or other namespace with that 
            class-namespace. This is most easily accomplished via the 
            <A href="help/topics/SymbolTreePlugin/SymbolTree.htm">Symbol Tree</A></P>
    </BLOCKQUOTE>

    <H3><A name="Set_External_Entry_Point"></A>Setting an External Entry Point</H3>

    <BLOCKQUOTE>
      <P>External Entry points can only be created at addresses that have at least one symbol. To
      set an external entry point:</P>

      <OL>
        <LI>Right click on a symbol and choose the <B>Edit Label</B> menu option.</LI>

        <LI>Check the <I>Entry Point</I> checkbox in the <B><A href="#AddEditDialog">Label</A></B>
        dialog.</LI>
      </OL>
    </BLOCKQUOTE>

    <H3><B><A name="Making_Label_Primary"></A>Making a Label Primary</B></H3>

    <BLOCKQUOTE>
      <P>Making a label primary gives it priority over other labels that are associated with the
      same address. The primary label is displayed by other Ghidra features instead of the address.
      For example, in the subroutine view, the subroutine names are primary labels. If another
      label were added and made the primary label, then the subroutine view will display that label
      instead of the label bearing the subroutine name.<BR>
      If a function exists at an address, its name is the primary label; if you set another label
      at this address to be primary, then the symbol for this label is removed, and the function is
      renamed to that label that you were editing.&nbsp; The function symbol must always be
      primary.</P>

      <P>To make a label primary:</P>

      <OL>
        <LI>Right click on a symbol and choose the <B>Edit Label</B> menu option.</LI>

        <LI>Check the <I>primary</I> checkbox in the <B><A href="#AddEditDialog">Label</A></B>
        dialog.</LI>
      </OL>
    </BLOCKQUOTE>

    <H3><A name="Set_Operand_Label"></A>Selecting a referenced Label for an Operand</H3>

    <BLOCKQUOTE>
      <P>Referenced labels appear in instruction operands. By default, the primary label associated with the 
      primary reference from an operand will be displayed within the operand. 
      To have the operand display a different label corresponding to the primary memory reference:</P>

      <OL>
        <LI>Right click on the operand symbol and choose the <B>Set Associated Label...</B> menu option from the
        pop-up menu.  This action only appears if the primary reference is a memory reference.</LI>

        <LI>Choose a label from the drop-down list on the <B><A href="#OperandLabelDialog">Set
        Label</A></B> dialog or type in a name for a new label that will appear at the referred-to
        address.</LI>
      </OL>
    </BLOCKQUOTE>

    <P class="providedbyplugin">Provided by: the <B><I>Edit Labels</I></B> Plugin</P>

    <H3><A name="Show_Label_History"></A>Show Label History</H3>

    <BLOCKQUOTE>
      <P>You can show the history of changes on labels at a given address. You can also search the
      label history for all lables looking for old label names that no longer exist.&nbsp; Either
      way, a dialog is shown containing a table of lable changes. The "Action" column indicates
      whether the label was added, removed, or renamed. If the label was renamed, the "Label"
      column shows the old name renamed to the new name. The "User" is the user who made the
      change. The "Modification Date" is when the change was made. Labels that were added as a
      result of disassembly are not recorded in the history; however, if you rename a default
      label, you will see an entry in the table, as shown below.</P>

      <P><I><IMG src="help/shared/note.png" border="0">A column for "Address" shows up in the
      table if you are viewing the history of changes on labels at all addresses.</I></P>
    </BLOCKQUOTE>

    <TABLE border="0" width="100%">
      <TBODY>
        <TR>
          <TD align="center" width="100%"><IMG src="images/ShowLabelHistory.png" border="0"></TD>
        </TR>
      </TBODY>
    </TABLE>

    <BLOCKQUOTE>
      <P>To display the history of label changes at a specific address,</P>

      <OL>
        <LI>Right mouse click on a label (either in the label field or the operand field).</LI>

        <LI>Choose the <B>Show Label History</B> option.</LI>
      </OL>

      <P><IMG src="help/shared/tip.png" border="0">You can sort the label history by any of the
      columns and in ascending or descending order. By default, the history is sorted by ascending
      modification date (i.e., oldest date first). You can also reorder the columns by dragging the
      header to another column position.</P>

      <P><A name="Show_All_History"></A> To seach for label history for a past or present label
      name:<BR>
      </P>

      <OL>
        <LI>Select <SPAN style="font-weight: bold;">Search</SPAN><IMG src="help/shared/arrow.gif"
        border="0"><B>Label History</B>...</LI>
      </OL>

      <P align="center"><IMG alt="" src="images/LabelHistoryInputDialog.png"></P>

      <OL start="2">
        <LI>
          A dialog is displayed so that you can enter a label name (or part of a label
          name)&nbsp;&nbsp; 

          <UL>
            <LI>Enter a string you would like to see matches for.</LI>

            <LI>To display the label history for all the label changes, leave the field blank.</LI>
          </UL>
        </LI>

        <LI>
          Select the OK button or press the &lt;Enter&gt; key in the text field. 

          <UL>
            <LI>If label history was found, a dialog similar to the one shown above is displayed
            with the addition of an "Address" column. The input dialog remains displayed if no
            label history was found.</LI>

            <LI>From the label history dialog, you can navigate to each address by clicking on the
            row in the table.</LI>
          </UL>
        </LI>
      </OL>
    </BLOCKQUOTE>

    <P class="providedbyplugin">Provided by: the <B><I>Edit Labels</I></B> Plugin</P>

    <P class="relatedtopic">Related Topics:</P>

    <UL>
      <LI><A href="help/topics/SymbolTablePlugin/symbol_table.htm">Symbol Table</A></LI>

      <LI><A href="help/topics/SymbolTreePlugin/SymbolTree.htm">Symbol Tree</A></LI>

      <LI><A href="FieldNames.htm">Edit Field Names</A><BR>
      </LI>
    </UL><BR>
    <BR>
    <BR>
    <BR>
    <BR>
    <BR>
  </BODY>
</HTML>
